[% setvar title Subroutines: Extend subroutine contexts to include name parameters and lazy arguments %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>Subroutines: Extend subroutine contexts to include name parameters and lazy arguments</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Damian Conway &lt;<a href='mailto:damian@conway.org'>damian@conway.org</a>&gt;
  Date: 17 Aug 2000
  Last Modified: 25 Sep 2000
  Mailing List: <a href='mailto:perl6-language-subs@perl.org'>perl6-language-subs@perl.org</a>
  Number: 128
  Version: 4
  Status: Frozen</pre>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>This RFC proposes that subroutine argument context specifiers be
extended in several ways, including allowing parameters to be typed and
named, and that a syntax be provided for binding arguments to named
parameters.</p>
<a name='CHANGES'></a><h1>CHANGES</h1>
<p>Added section describing named parameter interaction with named higher-order
function placeholders.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p>It is proposed that the existing subroutine &quot;prototype&quot; mechanism
be replaced by optional formal parameter lists that allow parameters
to be named and their contexts specified.</p>
<p>The syntax for this would be:</p>
<pre>        sub subname ( type context(s) parameter_name : parameter_attributes ,
                      type context(s) parameter_name : parameter_attributes ,
                      type context(s) parameter_name : parameter_attributes ;
                      # end of required parameters
                      type context(s) parameter_name : parameter_attributes ,
                      # etc.
                    ) : subroutine_attributes
        { body }</pre>
<p>Each of the four components of a parameter specification -- type,
context, name, and attributes -- would be optional.</p>
<a name='Contexts'></a><h2>Contexts</h2>
<p>The context specifiers would be:</p>
<pre>        $       parameter is scalar
        @       parameter is array (eats remaining args)
        %       parameter is hash (eats remaining args)
        /       parameter is qr'd string
        &amp;       parameter is subroutine reference or block
        *       parameter is typeglob (assuming they still exist)
        &quot;&quot;      parameter is bareword or character string
	()	parameter is an explicitly parenthesized list</pre>
<p>Note that any of these specifiers may appear in any position in a
parameter list (especially <code>&amp;</code>, which would no longer be constrained to
the first position).</p>
<p>The following prefix context modifier would be available:</p>
<pre>        \             parameter must be a reference,
                      argument is magically en-referenced if necessary</pre>
<p>The following context attributes would be available:</p>
<pre>        :lazy         argument is lazily evaluated

        :uncurried    (&amp; only) terminate curry propagation on argument

        :noautoviv    that is a (possibly nested) hash element or array
                      element is not autovivified.

	:repeat{m,n}  argument is variadic within the specified range</pre>
<p>The following subsections describe each of these in detail.</p>
<p>The following grouping operator would also be available:</p>
<pre>        (...)   specifies that the argument(s) are to be 
                treated collectively (i.e. by modifiers and attributes)</pre>
<a name='Automagically en-referenced arguments'></a><h3>Automagically en-referenced arguments</h3>
<p>The <code>\</code> modifier causes the modified parameter to automagically
convert its corresponding argument to a reference without list flattening.
The most common usage is in passing hashes and arrays as a single argument.</p>
<p>Note that the semantics of <code>\</code> attribute would be altered
slightly from those of Perl 5, so that a reference is <i>always</i> passed for
that parameter. It would, of course, retain its magical
en-referencing coercion:</p>
<pre>        \$         argument must be scalar ref or start with $
                   scalar var magically en-referenced

        \@         argument must be array ref or start with @,
                   array var magically en-referenced

        \%         argument must be hash ref of start with %,
                   hash var magically en-referenced

        \/         argument must be qr'd string or /.../ or m/.../
                   /.../ or m/.../ magically qr'd to en-reference

        \&amp;         arg must be sub reference, curried function, or block
                   block converted to anonymous sub ref

        \*         argument must be typeglob ref of start with *,
                   typeglob magically en-referenced

        \&quot;&quot;        argument must be a string reference or a bareword,
                   bareword magically stringified and en-referenced

        \()        argument must be a parenthesized list or an anonymous
                   list constructor
                   parenthesized list is magically en-referenced</pre>
<a name='Lazy evaluation'></a><h3>Lazy evaluation</h3>
<p>If the <code>lazy</code> attribute is used for a particular parameter, that parameter
is lazily evaluated. This means that it is only evaluated when the
corresponding named parameter (see below) -- or the corresponding element
of @_ -- is first accessed in some way, after which the evaluated value
is stored in the element in the usual way. Passing the parameter to another
subroutine or returning it as an lvalue does not count as an access.
Evaluating it in an <code>eval</code> block always counts.</p>
<p>If the <code>lazy</code> attribute is applied to a <code>@</code> parameter (which eats the
remaining arguments), those remaining arguments are not evaluated
until the corresponding element of the array is accessed. Iteration
through such an array (i.e. in a <code>for</code> or <code>foreach</code>) only evaluates
one element per iteration.</p>
<p>If the <code>lazy</code> attribute is applied to a <code>%</code> parameter (which eats the
remaining arguments), the odd arguments (that are mapped to keys) are
immediately evaluated, but the even arguments (that map to values)
are not evaluated until the corresponding entry of the hash is accessed.
Iteration through such a hash (i.e. via <code>each</code> or <code>values</code>) only
evaluates one element per iteration.</p>
<p>For example:</p>
<pre>        sub firstdef(@:lazy) { defined($_) &amp;&amp; return $_ for (@_); }

        sub enervate($:lazy) { return $_[0] }

        sub Klingon::OP_TERNARY ($,$:lazy,$:lazy) 
        {
                if ( $_[0]-&gt;debaseToTerran() ) { return eval{$_[1]} }
                return eval{$_[2]};
        }</pre>
<p>Note the use of explicit <code>eval</code>'s in the last example, to force the
lazy arguments to evaluate before being returned.</p>
<a name='Controlling curry propagation'></a><h3>Controlling curry propagation</h3>
<p>RFC 23 proposes the addition of higher order functions, via argument/operand
placeholders. However, when a subroutine call includes a curried argument,
there is an ambiguity as to how far &quot;outwards&quot; the currying should propagate.
For example:</p>
<pre>        $num_nodes = traverse( $root, $sum += ^_ );</pre>
<p>might mean:</p>
<pre>        $num_nodes = sub{ traverse( $root, $sum += $_[0] ) };</pre>
<p>if currying continued to the outermost subroutine, or:</p>
<pre>        $num_nodes = traverse( $root, sub{$sum += $_[0]} );</pre>
<p>if it were restricted to the second argument.</p>
<p>As the former interpretation is the proposed default behaviour, some
syntactic means of requesting the latter interpretation is required.</p>
<p>It is proposed that a parameter context attribute -- <code>uncurried</code> -- be
added to handle this. Any parameter with the <code>uncurried</code> attribute would
prevent curry propagation to the surrounding subroutine call.
Thus, with the declaration:</p>
<pre>        sub traverse ($,$:uncurried);</pre>
<p>the call:</p>
<pre>        $num_nodes = traverse( $root, $sum += ^_ );</pre>
<p>would be equivalent to:</p>
<pre>        $num_nodes = traverse( $root, sub{$sum += $_[0]} );</pre>
<p>whereas the declaration:</p>
<pre>        sub traverse ($,$);</pre>
<p>would allow the curried argument to &quot;infect&quot; the entire surrounding call:</p>
<pre>        $num_nodes = sub{ traverse( $root, $sum += $_[0] ) };</pre>
<p>Note that the curry control only applies to the argument whose parameter
has the <code>uncurried</code> attribute. So:</p>
<pre>        sub traverse ($,$:uncurried);
        $num_nodes = traverse( ^_ , $sum += ^_ );</pre>
<p>means:</p>
<pre>        $num_nodes = sub { traverse( $_[0], sub{$sum += $_[0]} ) };</pre>
<p>The currying of the second argument is restricted to its argument slot, whilst
the currying of the first argument propagates outwards to encompass the entire
call to <code>traverse</code>.</p>
<a name='Variadic parameter lists'></a><h3>Variadic parameter lists</h3>
<p>It would be possible to specify parameter lists consisting of an
arbitrary number of specified parameters, using the variadic attribute
<code>repeat{<i>m</i>,<i>n</i>}</code>.</p>
<p>A parameter specification such as:</p>
<pre>	sub max($:repeat{2,20}) { ... }</pre>
<p>is equivalent to:</p>
<pre>	sub max($,$;$,$,$,$,$,$,$,$,$,$,$,$,$,$,$,$,$,$) { ... }</pre>
<p>That is, the <code>:repeat</code> attribute specifies the range of arguments that
the specified (scalar) parameter may represent.</p>
<p>If <i>m</i> is omitted it is zero; if <i>n</i> is omitted it is ~0 (maximum
unsigned integer).</p>
<p>For example, to specify a subroutine named <code>most</code> that takes two or more
magically enreferenced arrays and returns the one with the most elements:</p>
<pre>        sub most ( \@:ref repeat{2,} ) {
                my $max = shift;
                for (@_) {
                        $max = $_ if @$max &lt; @$_;
                }
                return @$max;
        }

        my @most = most @x, @y, @z;</pre>
<p>Or consider a subroutine that takes an alternating sequence of pairs of:</p>
<ul>
<li><a name='a lazily evaluated, non-curry-propagating scalar expressions, followed by'></a>a lazily evaluated, non-curry-propagating scalar expressions, followed by</li>
<li><a name='a bareword'></a>a bareword</li>
</ul>
<p>which then returns the stringification of the first bareword following any
expression that evaluates to true:</p>
<pre>        sub first ( ($:lazy uncurried, &quot;&quot;):repeat{,} ) {
                while (my ($true, $str) = splice @_, 0, 2) {
                        return $str if $true;
                }
        }

        my $first = first
                        $x &lt; 10 =&gt; little,
                        $x &lt; 20 =&gt; middle,
                        $x &lt; 30 =&gt; large;</pre>
<p>Note the use of grouping parentheses to cause the alternating
scalar/bareword sequence to be repeated.</p>
<a name='Preventing argument autovivification'></a><h3>Preventing argument autovivification</h3>
<p>When entries of nested hashes are passed to a subroutine:</p>
<pre>	func( $hash{key}{subkey}{subsubkey} );</pre>
<p>the intermediate entries in the nested hash (i.e. <code>$hash{key}</code> and
<code>$hash{key}{subkey}</code> in the above example) are atovivified, whether or
not the argument value itself is every accessed within the subroutine.
This is particularly galling if one or more of the nested hashes is
undefined, since it means the higher-level entries will have keys
created unnecessarily.</p>
<p>Specifying the <code>:noautoviv</code> attribute on a subroutine parameter
would cause the corresponding argument to be evaluated in a special
&quot;non-autovivifying&quot; context, unless it is used as an lvalue.</p>
<p>In such a non-autovivifying context, the non-existence of any
intermediate nested hash would cause the entire nested hash access to
immediately evaluate to <code>undef</code>, without any autovivification.</p>
<p>For example:</p>
<pre>        sub func1 ( $:noautoviv ) { ... }
        sub func2 ( $ )           { ... }

        my %hash;
        print keys %hash;                       # prints &quot;&quot;

        func1( $hash{key}{subkey} );
        print keys %hash;                       # prints &quot;&quot;

        func2( $hash{key}{subkey} );
        print keys %hash;                       # prints &quot;key&quot;</pre>
<p>If the parameter is used in an lvalue manner within the subroutine:
then autovivification is still applied (at the point where the argument
is used as an lvalue). For example:</p>
<pre>	sub func3 ( $:noautoviv ) {
		if (rand &gt; 0.5) { $_[0] = 0 }	# autovivifies argument
		else		{ print $_[0] }	# does not autovivify argument
	}


	sub func4 ( \$:noautoviv ) {	# always autovivifies (compiler warning)
		...
	}</pre>
<p>Note that this implies that <code>:noautoviv</code> parameters are automatically <code>:lazy</code>.</p>
<a name='Block parameters and arguments'></a><h3>Block parameters and arguments</h3>
<p>As noted above, <code>&amp;</code> parameters could appear in any position in the parameter
list, allowing raw blocks as arguments anywhere in the argument list.</p>
<p>It is proposed that raw blocks that are subroutine arguments need not
be separated by commas from adjacent arguments (on either side):</p>
<pre>        sub on ( &quot;&quot;, &amp; ) {
                $handler{$_[0]} = $_[1];
        }

        # and later...

        on Error::Numeric { die $@; };
        on Error::Range   { $_[0]--; };
        on Error          { ref($_[0])-&gt;handle(); };</pre>
<p>Furthermore, it is proposed that if a subroutine's parameter list ends
in a <code>&amp;</code> and the subroutine is called in a void context, that the
following semi-colon be optional:</p>
<pre>        on Error::Numeric {
                die $@;
        }

        on Error::Range {
                $_[0]--;
        }

        on Error {
                ref($_[0])-&gt;handle();
        }</pre>
<a name='Context classes'></a><h3>Context classes</h3>
<p>The revised syntax would also allow <i>context classes</i> to be specified.
A context class aggregates two or more alternative contexts, allowing
any one of them to be the context for corresponding argument.</p>
<p>For example:</p>
<pre>        sub mymap ([\/&amp;$], @) {...}
        </pre>
<p>Here, the first argument must be either a /.../ pattern (or qr), or a
block (or sub ref), or a scalar. In parsing that argument, the various
possible contexts are considered left-to-right and the first context
that allows the argument to be parsed is used.</p>
<p>Note that context classes may also have attributes:</p>
<pre>        sub mymap ([\/&amp;$]:lazy uncurried}, @) {...}</pre>
<p>In this example, no matter what the first argument is, it is lazily evaluated
and does not propagate currying.</p>
<p>A context class may only contain context specifiers that yield scalar
parameters. Hence, a context class may contain any of the following
specifiers (any of which may also have <code>lazy</code> or <code>uncurried</code> attributes):</p>
<pre>        $       /       \$      \/
        &amp;       *       \&amp;      \*      
        &quot;&quot;              \&quot;&quot;     \()
                        \@      \%</pre>
<p>but not:</p>
<pre>        @       %       ()</pre>
<p>A context class always yields a scalar parameter.</p>
<a name='Parameter names'></a><h2>Parameter names</h2>
<p>Each parameter may optionally (and independently) be given a name.
This name is specified after the parameter's context specifer.
The declaration of a parameter name creates a lexical variable of the
same name in the scope of the subroutine body. Named <code>@</code> and <code>%</code>
parameters create a lexical array or hash respectively. All other
named parameters create a lexical scalar.</p>
<p>For example:</p>
<pre>        sub doublemap (&amp;mapsub, @args) {        # creates my($mapsub,@args)
                my @mapped;
                push @mapped, $mapsub-&gt;(splice @args, 0, 2) while @args;
                return @mapped;
        }</pre>
<p>Note that the context specifier can still be any valid specifier:</p>
<pre>        sub lazymap ([&amp;\/$]mapper : lazy uncurried, $max, @args:lazy) {
                my @mapped;
                switch (ref $mapper) {
                        case 'CODE'  { push @mapped, $mapper-&gt;(shift)
                                                while @args &amp;&amp; $max--; }
                        case 'REGEX' { push @mapped, shift() =~ m/$mapper/
                                                while @args &amp;&amp; $max--; }
                        case ''      { push @mapped, $mapper
                                                while @args &amp;&amp; $max--; }
                }
                return @mapped;
        }</pre>
<a name='Named arguments'></a><h3>Named arguments</h3>
<p>It is further proposed that arguments may be passed by name, and that
named arguments may be passed in any order.</p>
<p>An argument would be associated with a named parameter by prefixing it
with a standard Perl label (i.e. an identifier-colon sequence). For example:</p>
<pre>        @mapped = doublemap(args: @list, mapsub: ^a+^b);</pre>
<p>On encountering labelled arguments in a subroutine call, the interpreter
would examine the named parameters to determine their contexts,
evaluate ththe labelled arguments (in left-to-right sequence) in the
context specified by the corresponding named parameters (or <i>not</i>
evaluate them for lazy contexts!). The resulting values would then be
assigned to the corresponding named parameters.</p>
<p>Any unlabelled arguments would then be evaluated and assigned (again in
left-to-right sequence) to any remaining parameters. Those nameless
evaluations would be carried out in the respective contexts specified by
the remaining parameters.</p>
<p>It would be an error to:</p>
<pre>        * Define two named parameters with the same name, unless they
          can be distinguished by context. 

        * Label two arguments with the same name, unless there are 
          two context-distinguishable named parameters of that name.</pre>
<p>If a subroutine was called with a labelled argument for which there was
no named parameter, the label would be ignored and the argument treated
as unlabelled, unless the subroutine had been declared with a
<code>strict_args</code> attribute.</p>
<a name='Interaction with named placeholders'></a><h3>Interaction with named placeholders</h3>
<p>It is further proposed that when named placeholders are used to curry a
function, the resulting subroutine would have named parameters. If the
curried function mixed named, ordinal, and anonymous placeholders, the
resulting subroutine would have a mixture of named and unnamed parameters.</p>
<p>For example:</p>
<pre>        my $selector = ^condition ? ^2 : ^_;</pre>
<p>would be equivalent to:</p>
<pre>        my $selector = sub ($condition,$,$) { $condition ? $_[2] : $_[1] };</pre>
<p>This would make currying out the condition clearer:</p>
<pre>        my $select_on_val = $selector-&gt;(condition: $val);</pre>
<a name='Types'></a><h2>Types</h2>
<p>It is proposed that parameters may be given types: either the name of
a class, or the name of a builtin type (such as 'ARRAY', 'HASH',
'CODE', etc.)</p>
<p>If a parameter has a type (<code>T</code>) then the following additional
constraints are placed upon it and its value:</p>
<ul>
<li><a name='1.'></a>1.</li>
<p>The parameter's specified (or implicit) context must yield a scalar value.</p>
<li><a name='2.'></a>2.</li>
<p>The scalar value of the bound argument (say, $val) must satisfy
<code>UNIVERSAL::isa($val,'T')</code>.</p>
<li><a name='3.'></a>3.</li>
<p>If the parameter is named, the corresponding lexical variable will be
typed to class <code>T</code>, unless <code>T</code> is the name of a built-in type:
'SCALAR', 'HASH', 'CODE', etc.  (and maybe even then, if typed lexicals
were to be extended to built-in types)</p>
<li><a name='4.'></a>4.</li>
<p>If the subroutine has the attribute <code>:multi</code>, then the typed parameter
takes part in the multiple dispatching of the subroutine (see forthcoming
RFC).</p>
</ul>
<p>For example:</p>
<pre>        sub traverse (Tree $root, $subref:uncurried) {...}</pre>
<p>This specifies that the first argument must be a Tree object, or an object of a
class derived from Tree. The corresponding lexical variable would be equivalent
to:</p>
<pre>        my Tree $root;</pre>
<a name='Using builtin type names'></a><h3>Using builtin type names</h3>
<p>The ability to specify the names of builtin types as parameter types offers
additional flexibility in controlling argument interpretation. For example,
the specification:</p>
<pre>        sub demo(ARRAY $a, @b) {...}    # version 1</pre>
<p>constrains the argument to be an array reference, but does not invoke a
magical en-referencing context, the way this would:</p>
<pre>        sub demo(\@a, @b) {...}         # version 2</pre>
<p>Thus, a call like:</p>
<pre>        demo(@LOL);</pre>
<p>will succeed under version 1 (binding $LOL[0] to $a,
and the rest of @LOL to @b), provided $LOL[0] is an array reference.</p>
<p>Under version 2, the call to <code>demo</code> would fail, since <code>\@LOL</code> will be
bound to $a and there will be nothing left to bind to @b.</p>
<a name='Banishment of the term &quot;prototype&quot;'></a><h2>Banishment of the term &quot;prototype&quot;</h2>
<p>It is further proposed that parameter lists <i>never</i> be referred to
as &quot;prototypes&quot;, and that use of the term be a flameworthy offence.
The preferred nomenclature would be &quot;parameter list&quot;, or perhaps
&quot;signature&quot;.</p>
<a name='MIGRATION ISSUES'></a><h1>MIGRATION ISSUES</h1>
<p>This proposal has the potential to break a small number of cases
where a backslashed context specifier would now match a reference
argument that it previously complained about.</p>
<p>Also, the suggested regularization of semantics for backslash means
that a <code>\$</code> argument is passed as a reference, not a value.</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>Definitely S.E.P.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>RFC 21 (v1): Replace <code>wantarray</code> with a generic <code>want</code> function</p>
<p>RFC 22 (v1): Builtin switch statement</p>
<p>RFC 23 (v2): Higher order functions</p>
<p>RFC 57 (v1): Subroutine prototypes and parameters</p>
<p>RFC 84 (v1): Replace =&gt; (stringifying comma) with =&gt; (pair constructor)</p>
<p>RFC 97 (v1): prototype-based method overloading</p>
<p>[Numerous other RFC's make use of, or reference to, this mechanism]</p>
</div>
